11장 MCP로 바깥 도구 연결하기 (입문판)

원서: 클로드 코드 완벽 가이드 (코드팩토리 최지호)

이 장에서 딱 3가지만 1. 클로드 코드가 대화창 밖 도구(깃허브·데이터베이스·파일)에 직접 손을 뻗게 해주는 게 MCP다. 2. MCP 서버를 등록하는 법 — 명령어 한 줄, 또는 설정 파일 직접 적기. 3. 연결 방식이 세 가지(stdio·SSE·HTTP)인데, 어떤 걸 골라야 하는지.

들어가며 — 이 장을 다 읽으면

이 장을 마치면 다음 세 가지를 할 수 있다.

• MCP가 무엇이고 왜 필요한지 일상 비유로 설명한다.
• MCP 서버를 명령어와 설정 파일 두 방법으로 따라 한다.
• stdio·SSE·HTTP 세 연결 방식을 구분하고, 상황에 맞게 고른다.

미리 알아두면 편한 것들이다. 몰라도 본문에서 다시 짚어준다.

• 클로드 코드 기본 사용법 (설치하고 실행하고 슬래시 명령 써보기)
• JSON 파일이 대충 어떻게 생겼는지 (이름표와 값이 짝지어진 형태)
• 터미널에 명령어 입력하기

11-1 MCP란? — 클로드에게 통역사를 붙여주기

이런 적 있죠?

깃허브에 올라온 이슈 하나를 클로드 코드에게 물어봤다고 해보자.

나: "깃허브 이슈 42번 내용 좀 알려줘"
클로드: "저는 깃허브에 직접 접근할 수 없습니다..."

그래서 결국 내가 브라우저를 열고, 이슈를 찾고, 내용을 복사해서, 다시 클로드에게 붙여넣는다. 한두 번이면 모를까 매번 이러면 귀찮다.

이게 바로 "클로드가 대화창 안에만 갇혀 있다"는 문제다. 클로드는 똑똑하지만, 내 컴퓨터 밖 세상(깃허브, 데이터베이스, 다른 서비스)에는 직접 손을 뻗지 못한다. 그 벽을 허물어 주는 게 바로 MCP다.

그게 바로 MCP다

MCP는 클로드 같은 AI가 대화창을 벗어나 바깥 도구와 직접 대화하게 해주는 약속(규칙)이다.

새 용어 — MCP(Model Context Protocol): AI를 외부 도구·데이터에 연결해주는 표준 약속. 마치 여러 나라 사람과 대화하게 해주는 '만능 통역사'와 같다.

조금 더 풀면 이렇다. MCP는 앤트로픽(클로드를 만든 회사)이 만든 오픈소스 프로토콜이다.

새 용어 — 프로토콜: 서로 다른 둘이 소통하기 위해 미리 정해둔 규칙. 사람끼리 "악수로 인사한다"고 약속해 둔 것과 비슷하다.

새 용어 — 오픈소스: 누구나 무료로 보고 쓸 수 있게 공개된 것. 동네 무료 도서관처럼 누구나 이용 가능하다.

만능 통역사 비유

외국에 혼자 가면 현지인과 말이 안 통한다. 그런데 통역사가 한 명 옆에 있으면? 어느 나라 사람을 만나도 대화가 된다.

MCP가 바로 클로드 코드를 위한 만능 통역사다. 깃허브든, 데이터베이스든, 파일 시스템이든 — 어떤 외부 서비스라도 MCP를 통하면 클로드가 직접 대화할 수 있다.

클라이언트-서버, 어렵지 않다

MCP는 클라이언트-서버 구조라고 한다. 말은 거창해도 식당과 똑같다.

새 용어 — 클라이언트: 무언가를 부탁하는 쪽. 식당에서 주문하는 '손님'이다. 여기서는 클로드 코드.

새 용어 — 서버: 부탁을 받아 처리해주는 쪽. 주문을 받아 요리해주는 '주방'이다. 여기서는 깃허브·DB 같은 도구를 담당하는 MCP 서버.

손님(클로드 코드)이 "이슈 42번 가져와"라고 주문하면, 주방(MCP 서버)이 깃허브에서 가져다준다. 그게 전부다.

MCP가 있으면 이렇게 달라진다

같은 질문, 전혀 다른 경험을 비교해 보자.

MCP 없을 때
나: "깃허브 이슈 42번 내용 알려줘"
클로드: "저는 깃허브에 접근할 수 없습니다..."
나: (브라우저 열기 → 이슈 찾기 → 복사 → 붙여넣기)

MCP 있을 때
나: "깃허브 이슈 42번 내용 알려줘"
클로드: (MCP로 깃허브에 직접 물어봄)
       "42번은 로그인 페이지 버그네요. 고치는 코드 만들어 드릴까요?"

MCP로 할 수 있는 일들

통역사가 붙으면 이런 일들이 가능해진다.

- 깃허브 이슈 만들기 / 조회하기 / 관리하기
- 데이터베이스에 "users 표 구조 알려줘"라고 직접 물어보기
- 원격 서버의 문제를 클로드가 직접 들여다보기
- 외부 API 문서를 실시간으로 참고하기
- 내 컴퓨터 파일을 읽고 프로젝트 관리하기

미니 시나리오 — 이럴 때 이렇게

상황: DB의 users 표가 어떻게 생겼는지 궁금하다.

이럴 때 MCP가 없으면, 내가 직접 DB에 접속해서 표 구조를 복사해 클로드에게 붙여넣어야 한다. MCP(데이터베이스 서버)를 붙여뒀다면? 그냥 이렇게 물으면 된다.

나: "우리 DB의 users 표 구조 알려줘"
클로드: "users 표는 id(정수), name(문자), email(문자)로 되어 있어요."

한 걸음 더 ▸ 여러 통역사를 동시에

클로드 코드는 여러 MCP 서버에 동시에 연결할 수 있다. 깃허브용 서버 하나, 데이터베이스용 서버 하나를 같이 붙여두면, 한 대화 안에서 둘 다 부려먹을 수 있다. "이 DB 문제 원인 찾아서, 깃허브에 이슈로 올려줘" 같은 연속 작업도 한 번에 된다.

잠깐 점검

• MCP가 Model Context Protocol의 약자라는 걸 기억하는가?
• MCP를 '만능 통역사'에 빗대어 설명할 수 있는가?
• MCP가 없을 때와 있을 때 무엇이 달라지는지 말할 수 있는가?
• MCP로 접근할 수 있는 외부 시스템 세 가지를 댈 수 있는가?

11-2 MCP 서버 설정하기 — 통역사 데려오는 두 가지 방법

이런 적 있죠?

통역사가 좋다는 건 알겠는데, 정작 "그래서 어떻게 데려오는데?"가 막막하다. MCP도 똑같다. 개념은 알았으니, 이제 실제로 서버 하나를 클로드 코드에 등록해 보자.

방법은 딱 두 가지다.

1. 명령어로 등록 — 터미널에 한 줄 입력 (빠르고 간편)
2. 설정 파일에 직접 적기 — .mcp.json 파일을 열어 손으로 작성

새 용어 — .mcp.json: MCP 서버 연결 정보를 적어두는 메모장 같은 설정 파일. 클로드 코드가 부팅할 때 이 파일을 읽어 "어떤 통역사들을 데려올지" 확인한다.

리모컨 등록 비유

새 TV 리모컨을 등록하는 상황을 떠올려 보자. 방법 A는 "자동 등록 버튼"을 한 번 누르는 것(명령어), 방법 B는 설명서를 보고 직접 코드 번호를 입력하는 것(파일 편집)이다. 결과는 같다. 어느 쪽이 편한지에 따라 고르면 된다.

방법 1 — 명령어로 등록하기 (가장 쉬운 길)

기본 문법은 이렇다.

claude mcp add <이름> <실행할 명령>

실제 예시를 보자. Context7이라는 MCP 서버를 등록하는 명령이다.

claude mcp add context7 -- npx -y @upstash/context7-mcp

새 용어 — npx: 프로그램을 따로 설치하지 않고 그 자리에서 바로 실행해주는 도구. 마치 정수기처럼, 물을 사다 쟁여두지 않아도 필요할 때 바로 받아 쓰는 것과 같다.

여기서 중간의 -- 두 줄이 중요하다. 잠시 뒤 '자주 하는 실수'에서 왜 그런지 짚는다.

방법 2 — 설정 파일에 직접 적기

같은 Context7 서버를 .mcp.json 파일에 손으로 적으면 이렇게 생겼다.

{
  "mcpServers": {
    "context7": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "env": {}
    }
  }
}

겁먹지 말자. 한 줄씩 풀면 이렇다.

• mcpServers: "여기 아래에 서버들을 적을게요"라는 큰 상자
• context7: 서버 이름 (내가 붙인 별명)
• type: 연결 방식 (여기선 stdio)
• command: 실행할 명령 (npx)
• args: 명령에 딸려가는 옵션들
• env: 필요하면 넣는 환경 설정. 없으면 비워둠 {}

새 용어 — args: 명령어에 추가로 붙이는 세부 지시. 커피 주문할 때 "샷 추가, 얼음 적게"처럼 명령 뒤에 붙는 옵션이다.

새 용어 — env(환경 변수): 서버에게 미리 알려주는 설정값. 예를 들어 "DB 주소는 여기야"처럼 도구가 동작하는 데 필요한 정보를 담는다.

before / after — 명령어 vs 파일, 결과는 같다

방법 1 (명령어 한 줄)
claude mcp add context7 -- npx -y @upstash/context7-mcp

방법 2 (파일에 직접)
.mcp.json 안에 위 JSON 블록 작성

→ 둘 다 결과는 똑같이 context7 서버가 등록됨

기본값은 stdio다

--transport라는 옵션을 따로 안 붙이면, 자동으로 stdio 방식으로 등록된다. 즉 "그냥 평범하게 추가"하면 stdio다. (stdio가 뭔지는 다음 절에서 자세히 본다.)

새 용어 — --transport(전송 방식): "어떤 길로 연결할래?"를 정하는 옵션. 집에 갈 때 버스·지하철·택시 중 고르는 것처럼, 연결 경로를 지정한다.

SSE 방식으로 등록하기

원격에 있는 서버를 계속 연결해 두는 SSE 방식은 이렇게 등록한다.

claude mcp add --transport sse context7 https://mcp.context7.com/sse

설정 파일로 적으면 이렇다. stdio와 달리 command/args 대신 url 주소를 적는다.

{
  "mcpServers": {
    "context7": {
      "type": "sse",
      "url": "https://mcp.context7.com/sse"
    }
  }
}

HTTP 방식으로 등록하기

원격 API를 필요할 때마다 부르는 HTTP 방식은 이렇게 등록한다.

claude mcp add --transport http context7 https://mcp.context7.com/sse

설정 파일 예시다.

{
  "mcpServers": {
    "context7": {
      "type": "http",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "env": {}
    }
  }
}

핵심만 기억하자. stdio는 내 컴퓨터에서 프로그램을 직접 돌리니 command/args를 적고, 원격(SSE)은 url 주소를 적는다. (셋의 차이는 다음 절에서 표로 정리한다.)

자주 하는 실수 — --를 빼먹는다

명령어로 등록할 때 가장 흔한 실수다.

잘못된 예
claude mcp add context7 npx -y @upstash/context7-mcp
→ 중간의 "-y"를 클로드가 "내 옵션인가?" 하고 헷갈려 함

올바른 예
claude mcp add context7 -- npx -y @upstash/context7-mcp
→ "--" 뒤는 전부 통째로 서버 실행 명령으로 넘겨줌

-- 두 줄은 "여기서부터는 내(claude) 옵션이 아니라 서버한테 줄 명령이야"라고 선을 긋는 표시다. 이 선을 안 그으면 -y 같은 옵션이 엉뚱하게 클로드의 옵션으로 읽힌다.

미니 시나리오 — 이럴 때 이렇게

상황: DB용 MCP 서버를 등록하는데, DB 주소를 미리 알려주고 싶다.

이럴 때는 설정 파일의 env에 주소를 적어 넣으면 된다.

{
  "mcpServers": {
    "my-db": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@my-org/db-mcp-server"],
      "env": { "DB_HOST": "localhost" }
    }
  }
}

env 안에 "DB_HOST": "localhost"라고 적으면, 서버는 "아, DB 주소는 localhost구나"하고 알아듣는다.

잠깐 점검

• claude mcp add의 기본 문법을 적을 수 있는가?
• .mcp.json의 기본 구조(mcpServers·type·command·args)를 설명할 수 있는가?
• 명령어로 추가할 때 --가 왜 필요한지 말할 수 있는가?
• stdio와 SSE의 설정 파일 모양이 어떻게 다른지 구분할 수 있는가?

11-3 세 가지 연결 방식 — 골라 쓰는 법

이런 적 있죠?

앞 절에서 stdio·SSE·HTTP 세 단어가 슬쩍 나왔다. "그래서 셋 중에 대체 뭘 써야 하는데?" 싶었을 거다. 이 절에서 그 답을 한 번에 정리한다. 결론부터 말하면, 잘 모르겠으면 stdio다.

배달 방식 비유

음식을 먹는 세 가지 방법으로 생각하면 쉽다.

• stdio = 집에서 직접 요리. 밖에 안 나가도 되고 제일 빠르다. (내 컴퓨터에서 실행)
• SSE = 뷔페 식당. 한 번 자리 잡으면 음식이 계속 나온다. (원격, 계속 연결)
• HTTP = 배달앱 주문. 먹고 싶을 때마다 주문하면 배달이 온다. (원격, 그때그때 요청)

새 용어 — stdio(표준 입출력): 내 컴퓨터에서 프로그램을 직접 돌려 주고받는 방식. 옆자리 동료와 직접 말로 대화하는 것처럼 가깝고 빠르다.

새 용어 — SSE(서버가 보내주는 알림): 서버가 먼저 데이터를 계속 밀어 보내주는 방식. 뉴스 속보 알림처럼, 내가 묻지 않아도 새 소식이 도착한다.

새 용어 — HTTP(요청-응답): 내가 물어볼 때만 답이 오는, 웹에서 가장 흔한 방식. 검색창에 입력하고 결과를 받는 것과 같다.

잠깐 ▸ "스트리밍이 된다"는 게 무슨 말일까

방금 HTTP를 "물어보면 답이 온다"고 했는데, 한 가지 더 알아두면 좋은 게 있다. MCP에서 쓰는 HTTP 서버는 답을 한꺼번에 몽땅 주는 게 아니라, 만들어지는 대로 조금씩 흘려보내며 줄 수도 있다. 이렇게 중간 결과를 흘려가며 주고받는 HTTP 서버를 따로 부르는 이름이 있다.

새 용어 — 스트리머블 HTTP(Streamable HTTP): 답을 다 끝낸 뒤 한꺼번에 주는 게 아니라, 만들어지는 대로 조금씩 흘려보내며 받는 HTTP 연결 방식. 컵라면을 다 끓여서 한 번에 내주는 것과, 물이 끓는 대로 조금씩 부어 주는 것의 차이와 같다.

말로만 보면 헷갈리니, 음식으로 다시 빗대 보자.

결과가 긴 작업일수록 이 차이가 크다. 한꺼번에 받는 방식은 다 끝날 때까지 기다리지만, 스트리머블 HTTP는 첫 조각이 나오는 순간부터 바로 받아 볼 수 있다.

보통 응답
요청 → (다 만들어질 때까지 대기) → 결과 한 번에 도착

스트리머블 HTTP
요청 → 조각1 → 조각2 → 조각3 → ... (만들어지는 대로 도착)

너무 깊이 외울 건 없다. "MCP의 HTTP 서버는 답을 조금씩 흘려보내며 줄 수도 있구나" 정도만 기억해 두면 충분하다.

한눈에 보는 비교표

상황별로 골라보기

로컬 파일을 읽고 쓰는 도구를 연결하고 싶다
→ stdio. 내 컴퓨터에서 직접 돌리니 인터넷도 필요 없고 빠르다.

원격 서버의 실시간 로그를 계속 지켜보고 싶다
→ SSE. 서버가 새 로그를 알아서 밀어 보내준다.

외부 서비스의 API를 가끔 불러 쓰고 싶다
→ HTTP. 필요할 때만 요청하면 되니 딱 맞는다.

등록된 서버 목록 확인하기

지금까지 어떤 통역사들을 데려왔는지 확인하려면 이 명령을 쓴다.

claude mcp list

실행하면 이렇게 보인다.

tosspayments-integration-guide: npx -y @tosspayments/integration-guide-mcp@latest
context7: https://mcp.context7.com/sse (SSE)

서버 이름과 연결 정보가 줄줄이 나온다. stdio는 실행 명령이, SSE는 주소와 (SSE) 표시가 보인다.

stdio가 왜 제일 많이 쓰일까

세 줄로 정리된다.

• 내 컴퓨터에서 바로 돌아 제일 빠르다.
• 인터넷이 필요 없다.
• 설정이 가장 간단하다 (--transport 안 붙이면 기본값).

그래서 "잘 모르겠으면 stdio로 시작"이 정답에 가깝다.

before / after — 잘못된 선택 vs 올바른 선택

상황: 실시간 빌드 상태를 계속 모니터링하고 싶다

잘못된 선택
→ HTTP. 그때그때 요청해야 해서, 상태가 바뀌어도 내가 물어볼 때까지 모름

올바른 선택
→ SSE. 빌드 상태가 바뀌는 순간 서버가 알아서 알려줌

미니 시나리오 — 이럴 때 이렇게

상황: 로컬 파일을 검사하는 린트 도구를 MCP로 붙이려 한다.

새 용어 — 린트 도구: 코드에서 실수나 어색한 부분을 자동으로 잡아주는 검사기. 글쓰기의 맞춤법 검사기와 같은 역할이다.

이럴 때는 stdio가 정답이다. 린트는 내 컴퓨터의 파일을 보는 일이라 인터넷이 필요 없고, 로컬로 직접 돌리면 가장 빠르기 때문이다.

claude mcp add my-linter -- npx -y @my-org/lint-mcp

한 걸음 더 ▸ 명령어로 추가 vs 파일로 추가, 언제 뭘?

두 방법은 결과가 같지만, 어울리는 상황이 다르다.

혼자 하나만 빨리 붙일 거면 명령어, 여러 개를 정리해 팀과 공유할 거면 파일 편집이 편하다.

한 걸음 더 ▸ MCP와 헷갈리기 쉬운 친구들

클로드 코드에는 MCP 말고도 도와주는 장치가 더 있다. 역할이 다르니 헷갈리지 말자.

MCP는 바깥과 연결하는 통역사, CLAUDE.md는 프로젝트 규칙을 적어두는 곳, 슬래시 명령은 자주 쓰는 작업을 단축키처럼 만드는 것이다. (CLAUDE.md와 슬래시 명령은 앞 장들에서 다뤘다.)

잠깐 점검

• stdio·SSE·HTTP를 각각 한 줄로 설명할 수 있는가?
• stdio가 가장 많이 쓰이는 이유 세 가지를 댈 수 있는가?
• claude mcp list로 무엇을 확인하는지 아는가?
• 주어진 상황에 맞는 연결 방식을 고를 수 있는가?

연습 문제

문제 1 — MCP 개념 (기본)

MCP가 없는 상태에서 클로드에게 "우리 DB의 users 표 구조 알려줘"라고 하면 어떻게 될까? MCP가 있으면 무엇이 달라질까?

문제 2 — 설정 파일 작성 (중급)

다음 조건으로 .mcp.json을 작성해 보자. - 서버 이름: my-db - 연결 방식: stdio - 실행 명령: npx - 옵션: -y, @my-org/db-mcp-server - 환경 설정: DB_HOST를 localhost로

{
  "mcpServers": {
    "my-db": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@my-org/db-mcp-server"],
      "env": { "DB_HOST": "localhost" }
    }
  }
}

문제 3 — 연결 방식 고르기 (심화)

다음 세 상황에서 어떤 방식을 골라야 할까? 이유도 함께 답해 보자. 1. 로컬 파일을 검사하는 린트 도구를 연결한다 2. 외부 결제 서비스의 API 문서를 가끔 참고한다 3. 빌드 상태를 실시간으로 지켜본다

문제 4 — 문제 해결 (심화)

claude mcp add로 서버를 추가했는데 claude mcp list에 안 보인다. 원인과 해결법을 세 가지 이상 들어 보자.

이 장 한 장 요약

• MCP는 클로드가 깃허브·DB·파일 같은 바깥 도구와 직접 대화하게 해주는 '만능 통역사'다. 앤트로픽이 만든 오픈소스 약속이고, 손님(클로드)-주방(MCP 서버) 구조다.
• 서버 등록은 두 가지 — 명령어(claude mcp add, 빠름)와 설정 파일(.mcp.json 직접 편집, 여러 개 한 번에). 명령어에선 --를 빼먹지 말 것.
• 연결 방식은 세 가지 — stdio(로컬, 빠름, 기본값)·SSE(실시간 알림)·HTTP(그때그때 요청). 잘 모르겠으면 stdio.
• 등록 확인은 claude mcp list.

더 알아보기

• MCP 공식 사이트: https://modelcontextprotocol.io — 프로토콜 공식 문서
• MCP 깃허브: https://github.com/modelcontextprotocol — 구현체와 SDK
• 앤트로픽 MCP 발표 글: https://www.anthropic.com/news/model-context-protocol
• 코드팩토리 깃허브: https://github.com/codefactory-co — 저자 예제 코드

참고: 본문의 서버 이름·주소·패키지(Context7, 토스페이먼츠 등)는 원서/노트 기준 예시이며, 최신 값과 사용 가능 여부는 클로드 코드 공식 문서에서 확인하자.

다음 장 예고: 다음 장에서는 클로드 코드를 더 깊이 다루는 주제로 넘어간다. 지금 몰라도 된다.